<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="tutorial.css">
<TITLE>
Line coverage
</TITLE>
</HEAD>
<BODY >
<A HREF="tutorial044.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="tutorial042.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc91">6.3</A>&nbsp;&nbsp;Line coverage</H2><UL>
<LI><A HREF="tutorial045.html#toc48">Compilation</A>
<LI><A HREF="tutorial045.html#toc49">Results</A>
</UL>

<A NAME="@default143"></A>
<A NAME="@default144"></A>
<A NAME="@default145"></A>
The line coverage library provides a means to ascertain exactly how
many times individual clauses are called during the evaluation of a
query.<BR>
<BR>
<A NAME="@default146"></A>
The library works by placing <EM>coverage counters</EM> at strategic
points throughout the code being analysed. These counters are
incremented each time the evaluation of a query passes them. There
are three locations in which coverage counters can be inserted.

	<TABLE CELLPADDING=10>
<TR><TD BGCOLOR="#DB9370">
	
	
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
At the beginning of a code block.
<LI CLASS="li-enumerate">Between predicate calls within a code block.
<LI CLASS="li-enumerate">At the end of a code block.
</OL>

	
	</TD>
</TR></TABLE>
	Locations where coverage counters can be placed
	
A code block is defined to be a conjunction of predicate calls. ie. a
sequence of goals separated by commas.<BR>
<BR>
As previously mentioned, by default, code coverage counters are
inserted before and after every subgoal in the code. For instance, in
the clause

	<TABLE CELLPADDING=10>
<TR><TD BGCOLOR="#CCCCFF">
	<BLOCKQUOTE CLASS="quote"><PRE>
p :- q, r, s.
</PRE></BLOCKQUOTE></TD>
</TR></TABLE>
four counters would be inserted: before the call to <CODE>q</CODE>, between
<CODE>q</CODE> and <CODE>r</CODE>, between <CODE>r</CODE> and <CODE>s</CODE>, and after
<CODE>s</CODE>:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
p :- point(1), q, point(2), r, point(3), s, point(4).
</PRE></BLOCKQUOTE>
This is the most precise form provided. The counter values do not only
show whether all code points were reached but also whether subgoals
failed or aborted (in which case the counter before a subgoal will
have a higher value than the counter after it). For example, the
result of running the above code is:
<BLOCKQUOTE CLASS="quote"><PRE>
p :- <SPAN STYLE="background-color:lime">43 </SPAN> q, <SPAN STYLE="background-color:lime">25 </SPAN> r, <SPAN STYLE="background-color:lime">25 </SPAN> s <SPAN STYLE="background-color:red">0 </SPAN> .
</PRE></BLOCKQUOTE>
which indicates that <CODE>q</CODE> was called 43 times, but succeeded only
25 times, <CODE>r</CODE> was called 25 times and succeeded always, and
<CODE>s</CODE> was called 25 times and never succeeded. Coverage counts of
zero are displayed in red (the final box) because they indicate
unreached code. The format of the display is explained in the next
section.<BR>
<BR>
<A NAME="toc48"></A>
<H3 CLASS="subsection"><A NAME="htoc92">6.3.1</A>&nbsp;&nbsp;Compilation</H3>
<A NAME="@default147"></A>
<A NAME="@default148"></A>
In order to add the coverage counters to code, it must be compiled with
the <A HREF="../bips/lib/coverage/ccompile-1.html"><B>ccompile/1</B></A><A NAME="@default149"></A>
predicate which can be found in the
<A HREF="../bips/lib/coverage/index.html"><B>coverage</B></A><A NAME="@default150"></A> library.<BR>
<BR>
The predicate <CODE>ccompile/1</CODE> (note the initial `c' stands for
coverage) can be used in place of the normal <CODE>compile/1</CODE>
predicate to compile a file with coverage counters.<BR>
<BR>
Here we see the results of compiling the <B>n-queens</B> example
given in the previous section.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- coverage:ccompile(queens).
coverage: inserted 22 coverage counters into module eclipse
foo.ecl    compiled traceable 5744 bytes in 0.00 seconds

Yes (0.00s cpu)
</PRE></BLOCKQUOTE>
Once compiled, predicates can be called as usual and will (by default)
have no visible side effects. Internally however, the counters will
be incremented as the execution progresses. To see this in action,
consider issuing the following query having compiled the previously
defined code using <CODE>ccompile/1</CODE>.
<BLOCKQUOTE CLASS="quote"><PRE>
?- queens([1,2,3,4,5,6,7,8,9], Out).
</PRE></BLOCKQUOTE>
The default behaviour of the <CODE>ccompile/1</CODE> predicate is to place
coverage counters as explained above, however such a level of detail
may be unnecessary. If one is interested in reachability analysis the
two argument predicate <CODE>ccompile/2</CODE> <A NAME="@default151"></A>
<A NAME="@default152"></A> can take a list of <CODE>name:value</CODE> pairs
which can be used to control the exact manner in which coverage
counters are inserted.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>&#8857;</B><DD CLASS="dd-description"> <FONT COLOR="#9832CC">See
</FONT><A HREF="../doc/bips/lib/coverage/ccompile-2.html"><FONT COLOR="#9832CC"><B>ccompile/2</B></FONT></A><A NAME="@default153"></A><FONT COLOR="#9832CC"> for a
full list of the available flags.</FONT>
</DL>
 In particular by specifying the
option <CODE>blocks_only:on</CODE>, counters will only be inserted at the
beginning and end of code blocks. Reusing the above example this would
result in counters at point(1) and point(4).
<BLOCKQUOTE CLASS="quote"><PRE>
p :- <SPAN STYLE="background-color:lime">43 </SPAN> q,  r,  s <SPAN STYLE="background-color:red">0 </SPAN> .
</PRE></BLOCKQUOTE>
This can be useful in tracking down unexpected failures by looking for
exit counters which differ from entry counters, for example.<BR>
<BR>
<A NAME="toc49"></A>
<H3 CLASS="subsection"><A NAME="htoc93">6.3.2</A>&nbsp;&nbsp;Results</H3>

<A NAME="@default154"></A> <A NAME="@default155"></A> To generate an html file
containing the coverage counter results issue the following query.
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- coverage:result(queens).
</PRE></BLOCKQUOTE>
This will create the result file <TT>coverage/queens.html</TT> which
can be viewed using any browser. It contains a pretty-printed form of
the source, annotated with the values of the code coverage counters as
described above. An example is shown in figure <A HREF="#fig:queens">6.1</A>.
<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<IMG SRC="tutorial025.gif">
</DIV>
<BR>
<BR>
<DIV CLASS="center">Figure 6.1: Results of running queens([1,2,3,4,5,6,7,8,9],_)</DIV><BR>
<BR>

<A NAME="fig:queens"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
<A NAME="@default156"></A> <A NAME="@default157"></A> For extra convenience the
predicate <CODE>result/0</CODE> is provided which will create results for
all files which have been compiled with coverage counters.<BR>
<BR>

	<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
	<DIV CLASS="center">
	<TABLE CELLPADDING=10>
<TR><TD BGCOLOR="#DB9370">
	
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A HREF="../bips/lib/coverage/result-0.html"><B>result/0</B></A><A NAME="@default158"></A><DD CLASS="dd-description"> Creates
results for all files which have been compiled with coverage counters.
<DT CLASS="dt-description"><A HREF="../bips/lib/coverage/result-1.html"><B>result/1</B></A><A NAME="@default159"></A><DD CLASS="dd-description"> This
predicate takes a single argument which is the name of the file to
print the coverage counters for.
<DT CLASS="dt-description"><A HREF="../bips/lib/coverage/result-2.html"><B>result/2</B></A><A NAME="@default160"></A><DD CLASS="dd-description">
<A NAME="@default161"></A> The result predicate has a two argument form, the
second argument defining a number of flags which control (amongst
other things)
<UL CLASS="itemize"><LI CLASS="li-itemize">
The directory in which to create the results file. Default:
<TT>coverage</TT>.
<LI CLASS="li-itemize">The format of the results file (html or text). Default:
<TT>html</TT>.
</UL>
</DL>

<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>&#8857;</B><DD CLASS="dd-description"> <FONT COLOR="#9832CC">See </FONT><A HREF="../bips/lib/coverage/index.html"><FONT COLOR="#9832CC"><B>coverage</B></FONT></A><A NAME="@default162"></A><FONT COLOR="#9832CC"> library
and </FONT><A HREF="../bips/lib/pretty_printer/index.html"><FONT COLOR="#9832CC"><B>pretty_printer</B></FONT></A><A NAME="@default163"></A><FONT COLOR="#9832CC">
library for more details</FONT>
</DL>


	</TD>
</TR></TABLE>
	</DIV>
	<BR>
<BR>
<DIV CLASS="center">Figure 6.2: Result generating commands</DIV><BR>
<BR>

	<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
<A NAME="@default164"></A> <A NAME="@default165"></A> Having
generated and viewed results for one run, the coverage counters can be
reset by calling
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- coverage:reset_counters.

Yes (0.00s cpu)
</PRE></BLOCKQUOTE>
<A NAME="@default166"></A>
<HR>
<A HREF="tutorial044.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="tutorial042.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
